<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Partial record storage and retrieval</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="am_misc.html" title="Chapter 4.  Access Method Wrapup" />
    <link rel="prev" href="am_misc_bulk.html" title="Retrieving and updating records in bulk" />
    <link rel="next" href="am_misc_struct.html" title="Storing C/C++ structures/objects" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Partial record storage and retrieval</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 4. 
		Access Method Wrapup
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="am_misc_struct.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="am_misc_partial"></a>Partial record storage and retrieval</h2>
          </div>
        </div>
      </div>
      <p>It is possible to both store and retrieve parts of data items in all
Berkeley DB access methods.  This is done by setting the
<a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structure passed to the
Berkeley DB method.</p>
      <p>The <a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag is based on the values of two fields
of the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structure: <span class="bold"><strong>dlen</strong></span> and <span class="bold"><strong>doff</strong></span>.  The value
of <span class="bold"><strong>dlen</strong></span> is the number of bytes of the record in which the
application is interested.  The value of <span class="bold"><strong>doff</strong></span> is the offset from
the beginning of the data item where those bytes start.</p>
      <p>For example, if the data item were <span class="bold"><strong>ABCDEFGHIJKL</strong></span>, a <span class="bold"><strong>doff</strong></span>
value of 3 would indicate that the bytes of interest started at
<span class="bold"><strong>D</strong></span>, and a <span class="bold"><strong>dlen</strong></span> value of 4 would indicate that the bytes
of interest were <span class="bold"><strong>DEFG</strong></span>.</p>
      <p>When retrieving a data item from a database, the <span class="bold"><strong>dlen</strong></span> bytes
starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the record are
returned, as if they comprised the entire record.  If any or all of the
specified bytes do not exist in the record, the retrieval is still
successful and any existing bytes are returned.</p>
      <p>When storing a data item into the database, the <span class="bold"><strong>dlen</strong></span> bytes
starting <span class="bold"><strong>doff</strong></span> bytes from the beginning of the specified key's
data record are replaced by the data specified by the <span class="bold"><strong>data</strong></span> and
<span class="bold"><strong>size</strong></span> fields.  If <span class="bold"><strong>dlen</strong></span> is smaller than <span class="bold"><strong>size</strong></span>, the
record will grow, and if <span class="bold"><strong>dlen</strong></span> is larger than <span class="bold"><strong>size</strong></span>, the
record will shrink. If the specified bytes do not exist, the record will
be extended using nul bytes as necessary, and the store call will still
succeed.</p>
      <p>The following are various examples of the put case for the
<a href="../api_reference/C/dbt.html#dbt_DB_DBT_PARTIAL" class="olink">DB_DBT_PARTIAL</a> flag. In all examples, the initial data item is 20
bytes in length:</p>
      <p>
        <span class="bold">
          <strong>ABCDEFGHIJ0123456789</strong>
        </span>
      </p>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <pre class="programlisting">size = 20
doff = 0
dlen = 20
data = abcdefghijabcdefghij

Result: The 20 bytes at offset 0 are replaced by the 20 bytes of 
data; that is, the entire record is replaced.

ABCDEFGHIJ0123456789 -&gt; abcdefghijabcdefghij </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 20
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 20 are replaced by the 10 bytes of 
data; that is, the record is extended by 10 bytes.

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJ0123456789abcdefghij </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 10
dlen = 5
data = abcdefghij

Result: The 5 bytes at offset 10 are replaced by the 10 bytes of 
data.

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJabcdefghij56789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 10
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 10 are replaced by the 10 bytes of 
data; that is, 10 bytes are inserted into the record.

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJabcdefghij0123456789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 2
dlen = 15
data = abcdefghij

Result: The 15 bytes at offset 2 are replaced by the 10 bytes of 
data.

ABCDEFGHIJ0123456789 -&gt; ABabcdefghij789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 0
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 0 are replaced by the 10 bytes of 
data; that is, the 10 bytes are inserted at the beginning of the 
record.

ABCDEFGHIJ0123456789 -&gt; abcdefghijABCDEFGHIJ0123456789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 0
doff = 0
dlen = 10
data = ""

Result: The 10 bytes at offset 0 are replaced by the 0 bytes of 
data; that is, the first 10 bytes of the record are discarded.

ABCDEFGHIJ0123456789 -&gt; 0123456789 </pre>
          </li>
          <li>
            <pre class="programlisting">size = 10
doff = 25
dlen = 0
data = abcdefghij

Result: The 0 bytes at offset 25 are replaced by the 10 bytes of 
data; that is, 10 bytes are inserted into the record past the end 
of the current data (\0 represents a nul byte).

ABCDEFGHIJ0123456789 -&gt; ABCDEFGHIJ0123456789\0\0\0\0\0abcdefghij </pre>
          </li>
        </ol>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="am_misc_bulk.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="am_misc.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="am_misc_struct.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Retrieving and updating records in bulk </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Storing C/C++ structures/objects</td>
        </tr>
      </table>
    </div>
  </body>
</html>
